Class ThinkGear

java.lang.Object
  ThinkGear

public class ThinkGear
extends java.lang.Object

Field Summary

static int	BAUD_115200
static int	BAUD_1200 Baud rate for use with Connect() and SetBaudrate().
static int	BAUD_2400
static int	BAUD_4800
static int	BAUD_57600
static int	BAUD_9600
static int	DATA_ALPHA1
static int	DATA_ALPHA2
static int	DATA_ATTENTION
static int	DATA_BATTERY Data type that can be requested from GetValue().
static int	DATA_BETA1
static int	DATA_BETA2
static int	DATA_DELTA
static int	DATA_GAMMA1
static int	DATA_GAMMA2
static int	DATA_MEDITATION
static int	DATA_POOR_SIGNAL
static int	DATA_RAW
static int	DATA_THETA
static int	MAX_CONNECTION_HANDLES Maximum number of Connections that can be requested before being required to free one.
static int	STREAM_5VRAW
static int	STREAM_FILE_PACKETS
static int	STREAM_PACKETS Data format for use with Connect() and SetDataFormat().
static int	TG_DATA_BLINK_STRENGTH

Method Summary

static int	Connect(int connectionId, java.lang.String serialPortName, int serialBaudrate, int serialDataFormat) Connects a ThinkGear Connection, given by connectionId, to a serial communication (COM) port in order to communicate with a ThinkGear module.
static void	Disconnect(int connectionId) Disconnects the ThinkGear Connection, given by connectionId, from its serial communication (COM) port.
static int	EnableAutoRead(int connectionId, int enable) Enables or disables background auto-reading of the connection.
static int	EnableBlinkDetection(int connectionId, int enable) Enables and disables the non-embedded eye blink detection. Non-embedded blink detection is disabled by default.
static int	EnableLowPassFilter(int connectionId, int rawSamplingRate) As a ThinkGear Connection reads and parses raw EEG wave values (via the TG_ReadPackets() function), the driver can automatically apply a 30Hz low pass filter to the raw wave data.
static void	FreeConnection(int connectionId) Frees all memory associated with the given ThinkGear Connection.
static int	GetDriverVersion() Returns a number indicating the version of the ThinkGear Communications Driver (TGCD) library accessed by this API.
static int	GetNewConnectionId() Returns an ID handle (an int) to a newly-allocated ThinkGear Connection object.
static double	GetValue(int connectionId, int dataType) Returns the most recently read value of the given dataType, which is one of the DATA_* constants defined above.
static int	GetValueStatus(int connectionId, int dataType) Returns Non-zero if the dataType was updated by the most recent call to GetValue().
static int	ReadPackets(int connectionId, int numPackets) Attempts to use the ThinkGear Connection, given by connectionId, to read numPackets of data from the serial stream.
static int	SendByte(int connectionId, int b) Sends a byte through the ThinkGear Connection (presumably to a ThinkGear module).
static int	SetBaudrate(int connectionId, int serialBaudrate) Attempts to change the baud rate of the ThinkGear Connection, given by connectionId, to serialBaudrate.
static int	SetDataFormat(int connectionId, int serialDataFormat) Attempts to change the data Packet parsing format used by the ThinkGear Connection, given by connectionId, to serialDataFormat.
static int	SetDataLog(int connectionId, java.lang.String filename) As a ThinkGear Connection reads and parses Packets of data from its serial stream, it may log the parsed data into a log file.
static int	SetStreamLog(int connectionId, java.lang.String filename) As a ThinkGear Connection reads bytes from its serial stream, it may automatically log those bytes into a log file.
static int	WriteDataLog(int connectionId, int insertTimestamps, java.lang.String msg) Writes a message given by msg into the Connection's Data Log.
static int	WriteStreamLog(int connectionId, int insertTimestamps, java.lang.String msg) Writes a message given by msg into the Connection's Stream Log.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAX_CONNECTION_HANDLES

public static final int MAX_CONNECTION_HANDLES

Maximum number of Connections that can be requested before being required to free one.

See Also:

Constant Field Values

BAUD_1200

public static final int BAUD_1200

Baud rate for use with Connect() and SetBaudrate().

See Also:

Constant Field Values

BAUD_2400

public static final int BAUD_2400

See Also:

Constant Field Values

BAUD_4800

public static final int BAUD_4800

See Also:

Constant Field Values

BAUD_9600

public static final int BAUD_9600

See Also:

Constant Field Values

BAUD_57600

public static final int BAUD_57600

See Also:

Constant Field Values

BAUD_115200

public static final int BAUD_115200

See Also:

Constant Field Values

STREAM_PACKETS

public static final int STREAM_PACKETS

Data format for use with Connect() and SetDataFormat().

See Also:

Constant Field Values

STREAM_5VRAW

public static final int STREAM_5VRAW

See Also:

Constant Field Values

STREAM_FILE_PACKETS

public static final int STREAM_FILE_PACKETS

See Also:

Constant Field Values

DATA_BATTERY

public static final int DATA_BATTERY

Data type that can be requested from GetValue().

See Also:

Constant Field Values

DATA_POOR_SIGNAL

public static final int DATA_POOR_SIGNAL

See Also:

Constant Field Values

DATA_ATTENTION

public static final int DATA_ATTENTION

See Also:

Constant Field Values

DATA_MEDITATION

public static final int DATA_MEDITATION

See Also:

Constant Field Values

DATA_RAW

public static final int DATA_RAW

See Also:

Constant Field Values

DATA_DELTA

public static final int DATA_DELTA

See Also:

Constant Field Values

DATA_THETA

public static final int DATA_THETA

See Also:

Constant Field Values

DATA_ALPHA1

public static final int DATA_ALPHA1

See Also:

Constant Field Values

DATA_ALPHA2

public static final int DATA_ALPHA2

See Also:

Constant Field Values

DATA_BETA1

public static final int DATA_BETA1

See Also:

Constant Field Values

DATA_BETA2

public static final int DATA_BETA2

See Also:

Constant Field Values

DATA_GAMMA1

public static final int DATA_GAMMA1

See Also:

Constant Field Values

DATA_GAMMA2

public static final int DATA_GAMMA2

See Also:

Constant Field Values

TG_DATA_BLINK_STRENGTH

public static final int TG_DATA_BLINK_STRENGTH

See Also:

Constant Field Values

Method Detail

GetDriverVersion

public static int GetDriverVersion()

Returns a number indicating the version of the ThinkGear Communications Driver (TGCD) library accessed by this API. Useful for debugging version-related issues.

Returns:

The TGCD library's version number.

GetNewConnectionId

public static int GetNewConnectionId()

Returns an ID handle (an int) to a newly-allocated ThinkGear Connection object. The Connection is used to perform all other operations of this API, so the ID handle is passed as the first argument to all functions of this API. When the ThinkGear Connection is no longer needed, be sure to call FreeConnection() on the ID handle to free its resources. No more than MAX_CONNECTION_HANDLES Connection handles may exist simultaneously without being freed.

Returns:

-1 if too many Connections have been created without being freed by FreeConnection().

SetStreamLog

public static int SetStreamLog(int connectionId,
                               java.lang.String filename)

As a ThinkGear Connection reads bytes from its serial stream, it may automatically log those bytes into a log file. This is useful primarily for debugging purposes. Calling this function with a valid filename will turn this feature on. Calling this function with an invalid filename, or with filename set to NULL, will turn this feature off. This function may be called at any time for either purpose on a ThinkGear Connection.

Parameters:

connectionId - The ID of the ThinkGear Connection to enable stream logging for, as obtained from GetNewConnectionId().

filename - The name of the file to use for stream logging. Any existing contents of the file will be erased. Set to NULL to disable stream logging by the ThinkGear Connection.

Returns:

-1 if connectionId does not refer to a valid ThinkGear Connection ID handle.

SetDataLog

public static int SetDataLog(int connectionId,
                             java.lang.String filename)

As a ThinkGear Connection reads and parses Packets of data from its serial stream, it may log the parsed data into a log file. This is useful primarily for debugging purposes. Calling this function with a valid filename will turn this feature on. Calling this function with an invalid filename, or with filename set to NULL, will turn this feature off. This function may be called at any time for either purpose on a ThinkGear Connection.

Parameters:

connectionId - The ID of the ThinkGear Connection to enable data logging for, as obtained from GetNewConnectionId().

filename - The name of the file to use for data logging. Any existing contents of the file will be erased. Set to NULL to disable stream logging by the ThinkGear Connection.

Returns:

-1 if connectionId does not refer to a valid ThinkGear Connection ID handle.

Connect

public static int Connect(int connectionId,
                          java.lang.String serialPortName,
                          int serialBaudrate,
                          int serialDataFormat)

Connects a ThinkGear Connection, given by connectionId, to a serial communication (COM) port in order to communicate with a ThinkGear module. It is important to check the return value of this function before attempting to use the Connection further for other functions in this API.

Parameters:

connectionId - The ID of the ThinkGear Connection to connect, as obtained from GetNewConnectionId().

serialPortName - The name of the serial communication (COM) stream port. COM ports on PC Windows systems are named like '\\.\COM4' (remember that backslashes in strings in most programming languages need to be escaped), while COM ports on Windows Mobile systems are named like 'COM4:' (note the colon at the end). Linux COM ports may be named like '/dev/ttys0'. Refer to the documentation for your particular platform to determine the available COM port names on your system.

serialBaudrate - The baudrate to use to attempt to communicate on the serial communication port. Select from one of the BAUD_* constants defined above, such as BAUD_9600 or BAUD_57600. BAUD_9600 is the typical default baud rate for standard ThinkGear modules.

serialDataFormat - The type of ThinkGear data stream. Select from one of the STREAM_* constants defined above. Most applications should use STREAM_PACKETS (the data format for Embedded ThinkGear modules). STREAM_5VRAW is supported only for legacy non-embedded purposes.

Returns:

-1 if connectionId does not refer to a valid ThinkGear Connection ID handle.

ReadPackets

public static int ReadPackets(int connectionId,
                              int numPackets)

Attempts to use the ThinkGear Connection, given by connectionId, to read numPackets of data from the serial stream. The Connection will (internally) "remember" the most recent value it has seen of each possible ThinkGear data type, so that any subsequent call to GetValue() will return the most recently seen values. Set numPackets to -1 to attempt to read all Packets of data that may be currently available on the serial stream.

Parameters:

connectionId - The ID of the ThinkGear Connection which should read packets from its serial communication stream, as obtained from GetNewConnectionId().

numPackets - The number of data Packets to attempt to read from the ThinkGear Connection. Only the most recently read value of each data type will be "remembered" by the ThinkGear Connection. Setting this parameter to -1 will attempt to read all currently available Packets that are on the data stream.

Returns:

-1 if connectionId does not refer to a valid ThinkGear Connection ID handle.

GetValue

public static double GetValue(int connectionId,
                              int dataType)

Returns the most recently read value of the given dataType, which is one of the DATA_* constants defined above. Use ReadPackets() to read more Packets in order to obtain updated values. Afterwards, use GetValueStatus() to check if a call to ReadPackets() actually updated a particular dataType. NOTE: This function will terminate the program with a message printed to stderr if connectionId is not a valid ThinkGear Connection, or if dataType is not a valid DATA_* constant.

Parameters:

connectionId - The ID of the ThinkGear Connection to get a data value from, as obtained from GetNewConnectionId().

dataType - The type of data value desired. Select from one of the DATA_* constants defined above. Refer to the documentation of each constant for details of how to interpret its value.

Returns:

The most recent value of the requested dataType.

GetValueStatus

public static int GetValueStatus(int connectionId,
                                 int dataType)

Returns Non-zero if the dataType was updated by the most recent call to GetValue(). Returns 0 otherwise.

Parameters:

connectionId - The ID of the ThinkGear Connection to get a data value from, as obtained from GetNewConnectionId().

dataType - The type of data value desired. Select from one of the DATA_* constants defined above. NOTE: This function will terminate the program with a message printed to stderr if connectionId is not a valid ThinkGear Connection, or if dataType is not a valid DATA_* constant.

Returns:

Non-zero if the dataType was updated by the most recent call to GetValue(). Returns 0 otherwise.

SendByte

public static int SendByte(int connectionId,
                           int b)

Sends a byte through the ThinkGear Connection (presumably to a ThinkGear module). This function is intended for advanced ThinkGear Command Byte operations. WARNING: Always make sure at least one valid Packet has been read (i.e. through the ReadPackets() function) at some point BEFORE calling this function. This is to ENSURE the Connection is communicating at the right baud rate. Sending Command Byte at the wrong baud rate may put a ThinkGear module into an indeterminate and inoperable state until it is reset by power cycling (turning it off and then on again). NOTE: After sending a Command Byte that changes a ThinkGear baud rate, you will need to call SetBaudrate() to change the baud rate of your connectionId as well. After such a baud rate change, it is important to check for a valid Packet to be received by ReadPacket() before attempting to send any other Command Bytes, for the same reasons as describe in the WARNING above.

Parameters:

connectionId - The ID of the ThinkGear Connection to send a byte through, as obtained from GetNewConnectionId().

b - The byte to send through. Note that only the lowest 8-bits of the value will actually be sent through.

Returns:

-1 if connectionId does not refer to a valid ThinkGear Connection ID handle.

SetBaudrate

public static int SetBaudrate(int connectionId,
                              int serialBaudrate)

Attempts to change the baud rate of the ThinkGear Connection, given by connectionId, to serialBaudrate. This function does not typically need to be called, except after calling SendByte() to send a Command Byte that changes the ThinkGear module's baud rate. See SendByte() for details and NOTE.

Parameters:

connectionId - The ID of the ThinkGear Connection to send a byte through, as obtained from GetNewConnectionId().

serialBaudrate - The baudrate to use to attempt to communicate on the serial communication port. Select from one of the BAUD_* constants defined above, such as BAUD_9600 or BAUD_57600. BAUD_9600 is the typical default baud rate for standard ThinkGear modules.

Returns:

-1 if connectionId does not refer to a valid ThinkGear Connection ID handle.

SetDataFormat

public static int SetDataFormat(int connectionId,
                                int serialDataFormat)

Attempts to change the data Packet parsing format used by the ThinkGear Connection, given by connectionId, to serialDataFormat. This function does not typically need to be called, and is provided only for special testing purposes.

Parameters:

connectionId - The ID of the ThinkGear Connection to send a byte through, as obtained from GetNewConnectionId().

serialDataFormat - The type of ThinkGear data stream. Select from one of the STREAM_* constants defined above. Most applications should use STREAM_PACKETS (the data format for Embedded ThinkGear modules). STREAM_5VRAW is supported only for legacy non-embedded purposes.

Returns:

-1 if connectionId does not refer to a valid ThinkGear Connection ID handle.

Disconnect

public static void Disconnect(int connectionId)

Disconnects the ThinkGear Connection, given by connectionId, from its serial communication (COM) port. Note that after this call, the Connection will not be valid to use with any of the API functions that require a valid ThinkGear Connection, except SetStreamLog(), SetDataLog(), Connect(), and FreeConnection(). Note that FreeConnection() will automatically disconnect a Connection as well, so it is not necessary to call this function unless you wish to reuse the connectionId to call Connect() again.

Parameters:

connectionId - The ID of the ThinkGear Connection to disconnect, as obtained from GetNewConnectionId().

FreeConnection

public static void FreeConnection(int connectionId)

Frees all memory associated with the given ThinkGear Connection. Note that this function will automatically call Disconnect() to disconnect the Connection first, if appropriate, so that it is not necessary to explicitly call Disconnect() before calling this function, unless you wish to reuse the connectionId without freeing it first.

Parameters:

connectionId - The ID of the ThinkGear Connection to disconnect, as obtained from GetNewConnectionId().

EnableAutoRead

public static native int EnableAutoRead(int connectionId, int enable)

Enables or disables background auto-reading of the connection. This has the following implications:
- Setting enable to anything other than 0 will enable background auto-reading on the specified connection. Setting enable to 0 will disable it.
- Enabling causes a background thread to be spawned for the connection(only if one was not already previously spawned), which continuously calls TG_ReadPacket( connectionId, -1 ) at 1ms intervals.
- Disabling will kill the background thread for the connection.
- While background auto-reading is enabled, the calling program can use TG_GetValue() at any time to get the most-recently-received value of any data type. The calling program will have no way of knowing when a value has been updated. For most data types other than raw wave value, this is not much of a problem if the program simply polls TG_GetValue() once a second or so.
- The current implementation of this function will not include proper data synchronization. This means it is possible for a value to be read (by TG_GetValue()) at the same time it is being written to by the background thread, resulting in a corrupted value being read. However, this is extremely unlikely for most data types other than raw wave value.
- While background auto-reading is enabled, the TG_GetValueStatus() function is pretty much useless. Also, the TG_ReadPackets() function should probably not be called.

Parameters:

connectionId - The connection to enable/disable background auto-reading on.

enable - Zero (0) to disable background auto-reading, any other value to enable.

Returns:

-1 if connectionId does not refer to a valid ThinkGear Connection ID handle.

-2 if unable to enable background auto-reading.

-3 if an error occurs while attempting to disable background auto-reading.

0 on success.

EnableBlinkDetection

public static native int EnableBlinkDetection(int connectionId, int enables)

Enables and disables the non-embedded eye blink detection. Non-embedded blink detection is disabled by default. NOTE: The constants and thresholds for the eye blink detection is adjusted for TGAM1 only.

Parameters:

connectionId - The connection to enable/disable background auto-reading on.

enable - Zero (0) to disable background auto-reading, any other value to enable.

Returns:

-1 if connectionId does not refer to a valid ThinkGear Connection ID handle.

-2 if unable to enable background auto-reading.

-3 if an error occurs while attempting to disable background auto-reading.

0 on success.

EnableLowPassFilter

public static native int EnableLowPassFilter(int connectionId, int rawSamplingRate)

As a ThinkGear Connection reads and parses raw EEG wave values (via the TG_ReadPackets() function), the driver can automatically apply a 30Hz low pass filter to the raw wave data. Subsequent calls to TG_GetValue() on TG_DATA_RAW will therefore return the filtered value. This is sometimes useful for visualizing (displaying) the raw wave when the ThinkGear is in an electrically noisy environment. This function only applies the filtering within the driver and does not affect the behavior of the ThinkGear hardware in any way. This function may be called at any time after calling TG_GetNewConnectionId(). Automatic low pass filtering is disabled by default. NOTE: Automatic low pass filtering is currently only applicable to ThinkGear hardware that samples raw wave at 512Hz (such as TGAM in MindSet). It is not applicable to hardware that samples at 128Hz or 256Hz and should NOT be enabled for those hardware.

Parameters:

connectionId - The ID of the ThinkGear Connection to disconnect, as obtained from GetNewConnectionId().

rawSamplingRate -Specify the sampling rate that the hardware is currently sampling at. Set this to 0 (zero) or any invalid rate at any time to immediately disable the driver's automatic low pass filtering. NOTE: Currently, the only valid raw sampling rate is 512 (MindSet headsets). All other rates will return -2.

Returns:

-1 if connectionId does not refer to a valid ThinkGear Connection ID handle.

-2 if rawSamplingRate is not a valid rate. Currently only a sampling rate of 512 (Hz) is valid which is the raw sampling rate of MindSet headset.

0 on success.

WriteDataLog

public static native int WriteDataLog(int connectionId, int insertTimestamp, java.lang.String msg)

Writes a message given by msg into the Connection's Data Log. Optionally the message can be written onto a new line preceded by a timestamp. The Connection's Data Log must be already opened by TG_SetDataLog(), otherwise this function returns an error.

Parameters:

connectionId - The ID of the ThinkGear Connection to disconnect, as obtained from TG_GetNewConnectionId().

insertTimestamp - If set to any non-zero number, a newline and timestamp are automatically prepended to the msg in the Stream Log file. Pass a zero for this parameter to disable the insertion of newline and timestamp before msg.

msg - The message to write into the Data Log File. For Data Log parsers to ignore the message as a human-readable comment instead of hex bytes, prepend a '#' sign to indicate it is a comment.

Returns:

-1 if connectionId does not refer to a valid ThinkGear Connection ID handle.

-2 if if Data Log for the @c connectionId has not been opened for writing via TG_SetDataLog().

0 on success.

WriteStreamLog

public static native int WriteStreamLog(int connectionId, int insertTimestamp, java.lang.String msg)

Writes a message given by @c msg into the Connection's Stream Log. Optionally the message can be written onto a new line preceded by a timestamp. The Connection's Stream Log must be already opened by TG_SetStreamLog(), otherwise this function returns an error.

Parameters:

connectionId - The ID of the ThinkGear Connection to disconnect, as obtained from TG_GetNewConnectionId().

insertTimestamp - If set to any non-zero number, a newline and timestamp are automatically prepended to the msg in the Stream Log file. Pass a zero for this parameter to disable the insertion of newline and timestamp before msg.

msg - The message to write into the Data Log File. For Data Log parsers to ignore the message as a human-readable comment instead of hex bytes, prepend a '#' sign to indicate it is a comment.

Returns:

-1 if connectionId does not refer to a valid ThinkGear Connection ID handle.

-2 if if Data Log for the @c connectionId has not been opened for writing via TG_SetDataLog().

0 on success.